<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <title>CruiseControl.NET : File Merge Task</title>
	    <link rel="stylesheet" href="styles/site.css" type="text/css" />
        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">	    
    </head>

    <body>
	    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
		    <tr>
			    <td valign="top" class="pagebody">
				    <div class="pageheader">
					    <span class="pagetitle">
                            CruiseControl.NET : File Merge Task
                                                    </span>
				    </div>
				    <div class="pagesubheading">
					    This page last changed on Jun 26, 2009 by <font color="#0050B2">csut017</font>.
				    </div>

				    <p>Most build processes interact with external tools that write their output to file (<em>e.g.</em> NUnit, FxCop, or NCover).  To make the output of these tools available to CruiseControl.NET to be used in the build process or displayed in the CruiseControl.NET web page or included in CruiseControl.NET emails, these files need to be merged into the CruiseControl.NET integration.</p>

<p>To merge these files, you need to include a <b>File Merge Task</b> in your CruiseControl.NET project.  To do so, you need to modify your <b>ccnet.config</b> file as follows:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;cruisecontrol&gt;</span>
   <span class="code-tag">&lt;project name=<span class="code-quote">"project"</span>&gt;</span>
      ...
      <span class="code-tag">&lt;publishers&gt;</span>
         <span class="code-tag">&lt;merge&gt;</span>
             <span class="code-tag">&lt;files&gt;</span>
                  <span class="code-tag">&lt;file&gt;</span><span class="code-tag"><span class="code-comment">&lt;!-- path to NUnit test file --&gt;</span></span><span class="code-tag">&lt;/file&gt;</span>
                  <span class="code-tag">&lt;file&gt;</span><span class="code-tag"><span class="code-comment">&lt;!-- path to FxCop file --&gt;</span></span><span class="code-tag">&lt;/file&gt;</span>
             <span class="code-tag">&lt;/files&gt;</span>
         <span class="code-tag">&lt;/merge&gt;</span>
      <span class="code-tag">&lt;/publishers&gt;</span>
   <span class="code-tag">&lt;/project&gt;</span>
<span class="code-tag">&lt;/cruisecontrol&gt;</span></pre>
</div></div>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>You should place your File Merge Tasks in the &lt;publishers /&gt; section of your <a href="Project Configuration Block.html" title="Project Configuration Block">Project Configuration Block</a> before your <a href="Xml Log Publisher.html" title="Xml Log Publisher">Xml Log Publisher</a>.</td></tr></table></div>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>The files processed by File Merge Task must be in XML format.</td></tr></table></div>

<p>Modify the contents of the <b>&lt;files&gt;</b> element to contain the path of the files that you wish to merge.  The file can be specified using an asterisk ("&#42;") wildcard in order to include multiple files that match the specified pattern (ie. "*<b>-results.xml</b>" will merge all files ending with the suffix "<b>-results.xml</b>").   The asterisk wildcard can only be used in the filename, not in the path.</p>

<p>If a relative <tt>&lt;file&gt;</tt> location is specified, this is relative to the <a href="Project Configuration Block.html#ProjectConfigurationBlock-workingDirectory">Project Working Directory</a>.</p>

<h3><a name="FileMergeTask-Mergeactions"></a>Merge actions</h3>

<p>Prior to CruiseControl.NET 1.5.0, all files specified in this task are merged into the build log (this is the default behaviour if no action is specified.) Since the build log is XML data, all data that is merged needed to be treated as XML data. If the data was XML, it would be merged without any problems, otherwise the data would be embedded inside a CDATA block.</p>

<p>With CruiseControl.NET 1.5.0 it is now possible to control how the merge will work. There are three available actions:</p>
<ul>
	<li>Merge: the default behaviour - merge to the build log as XML if possible, as CDATA if not possible</li>
	<li>CData: always merge to the build log in a CDATA block</li>
	<li>Copy: instead of merging the data into the build log, it will copy the specified files into a "build" folder under the artefacts folder for the project</li>
</ul>


<p>The following is an example of how to configure a "copy" action instead of merging:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;cruisecontrol&gt;</span>
   <span class="code-tag">&lt;project name=<span class="code-quote">"project"</span>&gt;</span>
      ...
      <span class="code-tag">&lt;publishers&gt;</span>
         <span class="code-tag">&lt;merge&gt;</span>
             <span class="code-tag">&lt;files&gt;</span>
                  <span class="code-tag">&lt;file&gt;</span><span class="code-tag"><span class="code-comment">&lt;!-- path to NUnit test file --&gt;</span></span><span class="code-tag">&lt;/file&gt;</span>
                  <span class="code-tag">&lt;file action=<span class="code-quote">"Copy"</span>&gt;</span><span class="code-tag"><span class="code-comment">&lt;!-- path to NUnit images --&gt;</span></span><span class="code-tag">&lt;/file&gt;</span>
             <span class="code-tag">&lt;/files&gt;</span>
         <span class="code-tag">&lt;/merge&gt;</span>
      <span class="code-tag">&lt;/publishers&gt;</span>
   <span class="code-tag">&lt;/project&gt;</span>
<span class="code-tag">&lt;/cruisecontrol&gt;</span></pre>
</div></div>

<p>The build folder will use the same name as the build label for the project. If this folder already exists, any files within this folder will be overwritten.</p>

<h3><a name="FileMergeTask-WhyarethemergedresultsnotshowingupintheProjectReportWebApplication%3F"></a>Why are the merged results not showing up in the Project Report Web Application?</h3>

<p>If you have set up the configuration for the <b>File Merge Task</b> as described above and you are still not ending up with the appropriate results showing up within the web application, please try the following steps:</p>
<ol>
	<li>Click the <b>original log</b> link and check to see if the merged content is included in the xml.  If it is missing then got onto step 2.  If it is present and is still not showing up in the web page then try emailing the <a href="mailto:ccnet-user@googlegroups.com">CCNet users list </a>.</li>
	<li>Have you put the File Merge Tasks in the &lt;publishers /&gt; section of your <a href="Project Configuration Block.html" title="Project Configuration Block">Project Configuration Block</a> before your <a href="Xml Log Publisher.html" title="Xml Log Publisher">Xml Log Publisher</a>?</li>
	<li>Check the folder that contains the files that should be merged.  If they are not there then you need to dig into your build script to find out why they aren't getting created.</li>
	<li>If the files are there but aren't getting merged, double-check your <b>ccnet.config</b> file.  Is the configuration specified correctly as specified above?  Remember that case matters in XML tag and attribute names.</li>
	<li>Check the <b>ccnet.log</b> file.  You should see Info-level log messages stating that the files have been merged.</li>
	<li>Does the file contain valid XML data?  The File Merge Task only expects to process XML files.  It will attempt to clean up non-XML files and write errors to the <b>ccnet.log</b> file, but it isn't always successful.</li>
</ol>



				    
                    			    </td>
		    </tr>
	    </table>
	    <table border="0" cellpadding="0" cellspacing="0" width="100%">
			<tr>
				<td height="12" background="http://confluence.public.thoughtworks.org//images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
			</tr>
		    <tr>
			    <td align="center"><font color="grey">Document generated by Confluence on Sep 29, 2009 20:59</font></td>
		    </tr>
	    </table>
    </body>
</html>